This page last changed on Jul 26, 2006 by stephen fenech.

Transport providers can be configured in 3 ways -

  1. Using an endpoint Uri that defines the scheme and connection information for the transport, such as tcp://localhost:12345. See Mule Endpoint URIs for more information. The URI consists of the protocol followed by transport specific information and then zero or more parameters to set as properties on the connector.
  2. Defining a connector configuration in Mule xml, Spring or any other supported configuration.
  3. Transport provider properties can be set on endpoints to customise the transport behaviour for a single endpoint instance.

The actual configuration parameters for each transport type are described in the Transports Guide for each particular transport. The following describes the common properties for all transports.

Standard Connector Properties

Property Description Default Required
name The identifying name of the connector   Yes
exceptionListener The exception listener to use when errors occur in the connector. org.mule.impl. DefaultExceptionStrategy Yes
receiverThreadingProfile This defines the threading properties and WorkManager to use when receiving events from the connector The defaultReceiverThreadingProfile set on the Mule Configuration Yes
dispatcherThreadingProfile This defines the threading properties and WorkManager to use when dispatching events from the connector The defaultDispatcherThreadingProfile set on the Mule Configuration Yes
disposeDispatcherOnCompletion Determines whether the connector caches a MessageDispatcher once one it is created for an endpoint or if a new one should be created for each dispatch request false Yes
connectionStrategy Is the object responsible for controlling how connection failures and retries are handled. The connectionStrategy can attempt to make a connection based on frequency, retry attempts, Jmx, or some other trigger. org.mule.providers. SingleAttemptConnectionStrategy Yes
serviceOverrides Is a map of service configuration values that can be used to override the default configuration for this transport. Service Overrides are described earlier in this document   No

For information about specific properties for a particular transport provider see the Transports Guide.

Connection Strategies

Connection strategies are used to configure how a connector behaves when it connection fails. Different strategies can be used to control how a reconnection is made based on reties, frequency, exceptions occurred or other factors such as only allowing a reconnect from Jmx.
A connection Strategy is configured on the connector using the <connection-strategy> element. When a <connection-strategy> element is added to a connector the strategy is applied to inbound and outbound connections. If you require different behaviour for inbound and outbound connections on the same connector you need to configure two connectors to handle inbound and outbound connections differently. For example, to configure a Tcp connector that will try to connect 3 times every 2 seconds if the connection is lost -

<connector name="tcp" className="org.mule.providers.tcp.TcpConnector">
    <connection-strategy className="org.mule.providers.SimpleRetryConnectionStrategy">
        <properties>
             <property name="retryCount" value="3"/>
             <property name="frequency" value="2000"/>
        </properties>
    <connection-strategy/>
</connector>

You can set a default connection strategy for all connectors on a Mule instance by setting the strategy in the <mule-environment-properties> element, i.e.

<mule-environment-properties>
    <connection-strategy className="org.mule.providers.SimpleRetryConnectionStrategy">
        <properties>
             <property name="retryCount" value="3"/>
             <property name="frequency" value="2000"/>
        </properties>
    <connection-strategy/>
</mule-environment-properties>

Customising Connection Strategies

Mule comes with a few basic connection strategies such as the the SimpleRetryConnectionStrategy shown above. However, you may need to implement your own. The UMOConnectionStrategy is an interface with one method -

public void doConnect(UMOConnectable connectable) throws FatalConnectException;

This method should attempt to call connect() on the UMOConnectable object, until the connection works or the connection policy implemented by the custom UMOConnectionStrategy fails. If the connection fails a FatalConnectException should be thrown to tell Mule that it cannot connect. No other exceptions including RuntimeExceptions should be thrown.

Connector Service Descriptors

Each transport has a service descriptor that describes what classes are used to construct the transport. The file is located in META-INF/services/org/mule/providers and the file has the same name as the transport protocol i.e. META-INF/services/org/mule/providers/tcp.

Using the TCP transport provider as an examples the file looks like -

connector=org.mule.providers.tcp.TcpConnector
dispatcher.factory=org.mule.providers.tcp.TcpMessageDispatcherFactory
message.receiver=org.mule.providers.tcp.TcpMessageReceiver
message.adapter=org.mule.providers.tcp.TcpMessageAdapter
inbound.transformer=org.mule.transformers.simple.ByteArrayToString
outbound.transformer=org.mule.transformers.simple.StringToByteArray
endpoint.builder=org.mule.impl.endpoint.SocketEndpointBuilder
Property Description Required
connector The class name of the UMOConnector implementation to use Yes if no connector.factory
connector.factory The class name of the factory that can be used to construct the UMOConnector instance if the 'connector' property is not set. The factory class must implement org.mule.util.ObjectFactory. No
dispatcher.factory The classname of the class that implements UMOMessageDispatcherFactory, which is used to construct UMOMessageDispatcher instances for this transport. If the transport provider only supports inbound communication this property is not set No
message.receiver The classname of the class that implements UMOMessageReceiver, which is used to register message listeners with the transport. If the transport provider only supports outbound communication this property is not set No
transaction.factory If this transport is transactional the property defines the class name of the UMOTransactionFactory implementation use to create transactions for this transport No
message.adapter The class name of the UMOMessageAdapter implementation used to provide generic access to information about the underlying message type for this transport Yes
inbound.transformer The default inbound transformer for this transport. This transformer will be used to transform incoming messages if there is no transformer configured on the endpoint using this transport. If the endpoint is inbound and it defines a transformer this value will be ignored. No
outbound.transformer The default outbound transformer for this transport. This transformer will be used to transform outgoing messages if there is no transformer configured on the endpoint using this transport. If the endpoint is outbound and it defines a transformer this value will be ignored. No
response.transformer The default response transformer for this transport. Transports may or may no use this transformer depending on whether the transport supports sending responses back from a request; such as http. This transformer will be used to transform response messages if there is no transformer configured on the response router for the current component. No
endpoint.builder The endpoint builder used to configure MuleEndpointURI instances for the transport. It is responsible for extracting information from URIs in a way understood by this connector. For example, the URI jms://topic:datafeed will be processed by the ResourceNameEndpointBuilder such that the endpoint address will be 'datafeed' and 'topic' will be set as the resourceInfo for the endpoint telling the Jms connector to use/create a topic called 'datafeed'. Yes
service.finder Some transport providers such as SOAP provide multiple, vendor-specific implementations of the transport such as Axis, Glue or XFire. The service finder class can be used to determine which implementation to use, often based on what's on the classpath. so for the endpoint URI soap:http//localhost/8080/services the SOAPServiceFinder will be used to see if Axis or Glue is on the classpath and will constuct the service accordingly. No
service.error If for any reason a transport connector cannot be constructed using an endpoint URI, an error message can be set here and a ConnectorFactoryException will be thrown with this message if an attempt is made to construct the connector from an URI (instead of configuring the connector explicitly in configuration) No

When an endpoint URI is processed by Mule, it's service descriptor is located using the endpoint protocol and the descriptor along with the information on the URI are used to create a connector and endpoint instance.

Overriding Service Properties

Each Mule transport has a Connector Service Descriptor for each protocol the transport supports that contains some of the properties listed above. Users can override any of these settings for a particular transports so that it's behaviour can be customised to suit a particular usage. For example the FileConnector reads individual files from a directory, but a developer could write a custom UMOMessageReceiver for the file connector to just read changes from an existing file.

Every connector has a serviceOverrides property which is a Map containing one or more of the service properties listed above. Continuing with the custom File Receiver example, a developer can override the 'message.reciever' Connector Service Descriptor property.

<connector name="myFileConnector" className="org.mule.providers.file.FileConnector">
    <properties>
        ...
        <map name="serviceOverrides">
            <property name="message.receiver" value="com.foo.MyFileReceiver"/>
        </map>
    </properties>
</connector>

Setting Default Connector values

For some transports its easy to set all configuration info for the transport in URI i.e. tcp://localhist:12345. For other transports such as Jms, the developer needs to set lots of configuration parameters to create the connection and it becomes difficult to set these parameters on the URI. One option is to pre-configre all connectors in a configuration file, which is fine for some scenarios, but there is also another option.
Mule allows for default properties to be defined for connectors that will be used in absence of the properties being set directly. The properties themselves are set using the name of the property for the connector pre-pended with the connector protocol. For example, to set a default value for the Jms jndiInitialFactory property -

<environment-properties>
    <property name="jms.jndiInitialFactory"
         value="org.codehaus.activemq.jndi.ActiveMQInitialContextFactory"/>
</environment-properties>

or

MuleManager.getInstance.setProperty("jms.jndiInitialFactory",
    "org.codehaus.activemq.jndi.ActiveMQInitialContextFactory");

These properties can be set on the MuleManager or Client.

For a more complete example see the Mule Cookbook: Configuring Multiple Jms Clients

Writing your own Transport

If you want to implement a custom Transport for Mule see Writing Mule Transport Providers.

Document generated by Confluence on Nov 27, 2006 10:27